Check out a free preview of the full A Tour of Web Capabilities course:
The "Permissions Policy & API" Lesson is part of the full, A Tour of Web Capabilities course featured in this preview video. Here's what you'd learn in this lesson:

Max introduces the Permissions-Policy spec, which allows a header to be set to turn on or off a capability for a specific origin or across multiple origins. This is useful for turning off capabilities and eliminating a malicious actor's ability to execute code in a browser console.

Get Unlimited Access Now

Transcript from the "Permissions Policy & API" Lesson

[00:00:00]
>> APIs are typically enabled by default on the main navigation. What's the main navigation? The HTML document that was loaded with your web app. But if you have iframes that are mostly coming from another origin, so cross-origin iframes, most of the time, it depends on the API, but most of the time, the API won't be available for the iframe.

[00:00:26] This was because it was used in the wrong way. For example, today, typically, ads are iframes. So then you have an ad in a newspaper that was reading your geolocation, or your sensors, or things like that. So today, if you have a website with cross-origin iframes, you have to apply, you have to opt in for those APIs, okay?

[00:00:57] So if you wanna turn a capability on or off, we do have a way to do that, because also, it's enabled by default. And probably you're thinking, I'm not going to use Bluetooth in my website. And you say, well, it's okay, if I'm not using it, what's the problem if my code is not using it?

[00:01:14] But anyone can go to the console and write some code and that code will be executed with your origin. Makes sense? It's not a big risk, but anyway, you can be a bank and then you can have a plugin, or someone can be injecting a script somehow and reading your user's location or something, using the permission from the bank's website.

[00:01:40] So you may wanna turn off from a security point of view the capability. For that, we have an spec known as permissions policy that has changed its name recently. Before, it was known as feature policy. The spec is not a JavaScript API, so that's why we won't cover it too much.

[00:02:00] I will show you how that works, but it's just an HTTP header. Where? From your server when you are serving the HTML, you can specify that header, it's called permissions-policy. And for iframes, it's an HTML attribute. So the same value that you can send as an HTTP header can be set as an attribute for iframes.

[00:02:23] This is how it looks like. So for example, permissions policy:geolocation=, and in parentheses, in this case, you can express self. That is, I'm enabling geolocation for my website, for my origin, and also for these other two, or three, or four, or infinite other domains. So in this case, you are kind of enabled cross-domain usage for geolocation.

[00:02:48] This is an HTTP header, not the JavaScript API. If you wanna remove the permission, you use the name of the capability equals empty parentheses. In that case, it's an empty list, so no one has access to geolocation on this particular domain. If you open the console, you try to use API, it will deny you access to the capability, because the server set so for this HTML, for this web app, okay?

[00:03:19] Make sense? You can define multiple policies at the same time in just one definition. Such as, in this case, we have geolocation, space, camera, space, picture-in-picture, that's another capability. So in this case, for geolocation, you have a declaration of domains. For camera, you have a star, meaning that anyone in this navigation load can access the camera and picture-in-picture is disabled.

[00:03:48] And also, you can express several permissions policy, HTTP headers in the same load. In this case, in another line, you also disable Bluetooth, okay? So with this, you can have final control over, which capabilities will be available for your website. And then we have permissions API. This is the first API that we will see, the real API, one of 36.

[00:04:18] It looks, I mean, the name is strong, right, permissions API, but it's chaos, actually. So the idea of the API was to bring all the permissions in one places. Because in the history of web capabilities, every API was different, okay? I think that the first real capability that we added was geolocation and the iPhone was the first one.

[00:04:48] When Steve Jobs presented the iPhone and Safari for the iPhone, and he was saying that web apps were the way to create apps. Apple at that point didn't have the app store or native apps, didn't have the idea of the app store and they were promoting web apps, the power of the web, okay, that an old Apple, anyway.

[00:05:08] And they added capabilities, they added Canvas for 2D drawing. And later on, they added geolocation, that was the first one, the first capability API that we've seen. And it was chaos to know if you had permission or not. And every new API that appeared in the market, a new capability API, has its own API.

[00:05:30] So that's why they created the Permissions API. What's the problem? That today, it depends on the browser. Some capabilities are in the API, in this one in permissions API and some are not, and you don't know which one is in and it's a really narrow sub list of options.

[00:05:51] What's the deal here? You call navigator permissions query and an object. In this case, with a name, such as the name I wanna check for geolocation. And then, we check the state of that response, the state is a string. It can be granted, so you're good to go.

[00:06:11] For this origin, you can use the Geolocation API. You can be prompt, which means we don't know yet. So next time you try it, we will prompt the user or denied. And if it doesn't support that permission at all, such as geolocation, now it says in this phone, in this device, we don't have a Geolocation API, it will throw an exception, okay?

[00:06:36] So it's nice, the problem is that is not available for every capability. So only for a few, and each browser has its own sub list. So I would argue that not a lot of web apps are actually using this API.