Contrôler les fonctionnalités du navigateur à l'aide de règles d'autorisation

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

Kevin K. Lee

Les règles d'autorisation, anciennement appelées "règles relatives aux fonctionnalités", permettent au développeur contrôler les fonctionnalités du navigateur disponibles pour une page, ses cadres iFrame sous-ressources, en déclarant un ensemble de règles que le navigateur doit appliquer. Ces les stratégies sont appliquées 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 multi-origines, et autorise au développeur de contrôler les accès propriétaires et tiers aux fonctionnalités du navigateur.

L'utilisateur décide en dernier lieu d'autoriser l'accès à des fonctionnalités plus performantes et doit donner 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 l'intention des parties, et évite à l'utilisateur de déterminer si la demande d'accès aux fonctionnalités est légitime ou non. Par exemple, en en bloquant la fonctionnalité de géolocalisation pour tous les tiers via les règles d'autorisation, le développeur peut être certain qu'aucun tiers n'aura accès au compte la géolocalisation.

Modifications apportées aux règles relatives aux autorisations

La règle d'autorisation était auparavant appelée "règle de fonctionnalité". Les concepts clés restent les mêmes, mais il y a des changements importants en plus du nom.

Utilisation des champs structurés

Les champs structurés fournissent un ensemble de structures de données courantes pour 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, Improving HTTP withstructured header fields.

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

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

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 en ajoutant l'origine à la liste des origines de l'en-tête ou en ajoutant un attribut allow à la balise iFrame. Conformément aux règles sur les autorisations, si vous ajoutez un frame 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 de règle d'autorisation, la liste d'origines a la valeur par défaut *. Si vous ajoutez l'attribut allow à l'iFrame, vous autorisez l'accès à cette fonctionnalité.

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

La règle de fonctionnalité peut toujours être utilisée après Chrome 88, mais sert d'alias pour la règle d'autorisation. Hormis la syntaxe, il n'existe aucune différence de logique. Si les en-têtes des règles d'autorisation et des règles relatives aux 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 dans lequel vous êtes le propriétaire d'un site Web et souhaitez contrôler la façon dont votre site et votre 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.example de confiance.
• Votre site diffuse é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 également l'attribut allow de manière explicite sur le tag iFrame du site de confiance:

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

Dans cet exemple, la liste d'origine de l'en-tête autorise uniquement 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 d'origine identique (your-site.example) est autorisé à utiliser la fonctionnalité sans utiliser l'attribut allow.
3. Un iFrame diffusé à partir d'un autre sous-domaine (subdomain.your-site-example) qui n'a pas été ajouté à la liste d'origine et dont l'attribut "allow" est défini sur le tag iFrame, ne peut pas utiliser cette fonctionnalité. Des sous-domaines différents sont considérés comme des sites d'origine unique, mais multi-origines.
4. Un iFrame multi-origine (trusted-site.example) qui a été 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 multi-origine (trusted-site.example) ajouté à la liste des origines, sans l'attribut allow, ne peut pas utiliser la fonctionnalité.
6. 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'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 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 caractéristiques, séparez-les par une virgule. Si vous indiquez plusieurs origines, séparez chaque origine de la liste par un espace. Pour les en-têtes listant une origine correspondant à une requête d'origine croisée, la balise iFrame doit inclure l'attribut allow.

Voici quelques exemples de paires clé-valeur:

• Syntaxe: [FEATURE]=* <ph type="x-smartling-placeholder">
  </ph>
  • Règle appliquée à toutes les origines
  • Exemple : geolocation=*
• Syntaxe: [FEATURE]=(self) <ph type="x-smartling-placeholder">
  </ph>
  • Règle appliquée à la même origine
  • Exemple : geolocation=(self)
• Syntaxe: [FEATURE]=(self [ORIGIN(s)]) <ph type="x-smartling-placeholder">
  </ph>
  • 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 pour https://your-site.example.
• Syntaxe: [FEATURE]=([ORIGIN(s)]) <ph type="x-smartling-placeholder">
  </ph>
  • 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 du intégrateur. Si ces autorisations ne sont pas accordées à la page de l'intégrateur, les iFrames intégrés dans cette page seront également bloqués, même s'ils sont ajoutés à la liste des origines, car les règles d'autorisation délèguent les autorisations. Vous pouvez également utiliser le jeton self.
• Syntaxe: [FEATURE]=() <ph type="x-smartling-placeholder">
  </ph>
  • 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 du même site, mais multi-origines. Par conséquent, l'ajout d'un sous-domaine à la liste des origines 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.

Différents chemins, tels que https://your-site.example et https://your-site.example/embed, sont considérés comme ayant la même origine, et il n'est pas nécessaire que des chemins différents figurent dans la liste des origines.

Attribut iFrame allow

Pour une utilisation multi-origine, un iFrame a besoin de l'attribut allow dans la balise pour pouvoir accéder à 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 iFrame

Par défaut, si un iFrame redirige vers une autre origine, les règles ne sont pas appliquées à l'origine à laquelle l'iFrame accède. En indiquant l'origine à laquelle l'iFrame accède dans l'attribut allow, la règle d'autorisation appliquée à l'iFrame d'origine sera appliquée à l'origine à laquelle l'iFrame est redirigé.

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

Pour la voir en action, accédez à la démonstration de la navigation dans iFrame.

Exemples de configurations de règles d'autorisation

Vous trouverez des exemples de 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 la sienne et tous les iFrames. Dans cet exemple, l'ensemble du code diffusé à partir de https://your-site.example et 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, avec l'ajout de l'origine à la liste des origines de l'en-tête.

Vous pouvez voir cette configuration dans la démonstration.

Fonctionnalité autorisée sur un lieu d'origine identique uniquement

Permissions-Policy: geolocation=(self)

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

Vous pouvez voir cette configuration dans la démonstration.

Fonctionnalité autorisée sur des origines identiques et multi-origines spécifiques

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

Cette syntaxe permet d'utiliser la géolocalisation à la fois pour vous-même (https://your-site.example) et pour https://trusted-site.example. N'oubliez pas d'ajouter explicitement l'attribut allow dans le 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. Seuls la page d'origine et le https://trusted-site.example qui figurent dans la liste des origines, et qui disposent de l'attribut "allow" dans le tag iFrame, auront accès à la fonctionnalité de l'utilisateur.

Vous pouvez voir cette configuration dans la démonstration.

Fonctionnalité bloquée sur toutes les origines

Permissions-Policy: geolocation=()

Si la liste des origines est vide, la fonctionnalité est bloquée pour toutes les origines. Vous pouvez voir cette configuration 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 Permissions Policy, avec certaines limites. Il reste des questions concernant l'implémentation d'une API JavaScript, et une proposition de déplacer la logique vers l'API Permissions a été élaborée. Rejoignez la discussion si vous avez des idées.

featurePolicy.allowsFeature(feature)

• Renvoie true si la fonctionnalité est autorisée à utiliser l'origine par défaut.
• Le comportement est le même pour les deux règles définies par une règle d'autorisation et par l'ancienne règle de fonctionnalité.
• 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 l'élément géographique est autorisé pour le point de départ spécifié.
• 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, contrairement aux règles relatives aux fonctionnalités. Cette méthode vous indique maintenant qu'il est possible que la caractéristique soit autorisée pour cette origine. Vous devez vérifier de nouveau si l'attribut allow est défini pour l'iFrame. Le développeur doit effectuer une vérification supplémentaire de l'attribut allow de l'élément iFrame afin de déterminer si la fonctionnalité est autorisée pour l'origine tierce.

Rechercher des éléments géographiques dans un iFrame avec l'objet element

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

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

featurePolicy.allowedFeatures()

• Affiche la liste des caractéristiques autorisées pour l'utilisation de l'origine par défaut.
• Le comportement est identique pour les deux règles définies par les règles d'autorisation et les règles relatives aux 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 les règles d'autorisation et les règles relatives aux fonctionnalités

Intégration des outils pour les développeurs Chrome

Découvrez comment fonctionnent les règles d'autorisation dans les outils de développement.

1. Ouvrez les 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 cadre que vous souhaitez inspecter. La liste des fonctionnalités que le cadre sélectionné est autorisé à utiliser s'affiche, ainsi que la liste des fonctionnalités bloquées dans ce cadre.

Migration de Feature-Policy

Si vous utilisez actuellement l'en-tête Feature-Policy, vous pouvez suivre la procédure ci-dessous pour migrer vers les règles d'autorisation.

Remplacer les en-têtes de la règle de fonctionnalité par des en-têtes de la règle d'autorisation

Étant donné que les en-têtes des 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 sont compatibles depuis Chrome 88, vous pouvez mettre à jour les en-têtes existants sans risque.

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

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

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 l'élément document qui la contient. La méthode element.allowsFeature(feature) tient compte de 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 une nouvelle fois l'attribut allow dans le tag 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 cohérent pour les applications Web. Par ailleurs, 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 l'indicateur est activé, vous pouvez observer les cas de non-respect des règles d'autorisation dans les outils de développement, sous l'onglet "Application" :

L'exemple suivant montre comment construire 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 cas de non-respect des règles qui se produit dans ce frame en configurant un point de terminaison nommé "default". comme dans l'exemple ci-dessus. Les sous-frames 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:

• Spécifications des règles d'autorisation
• Explication des règles d'autorisation
• une liste de fonctionnalités contrôlées par des règles ;