Source code
Revision control
Copy as Markdown
Other Tools
# Permission Manager
The Firefox permission manager offers a simple way to store user preferences
(“permissions” or “exceptions”) on a per-origin basis. On the most basic level,
a permission consists of the following:
1. The **origin** for which the permission applicable. This could for example be
2. The permission **type**. This can be an arbitrary string, for example “geo”
to allow geolocation access on the specified site.
3. The permission **value**. Unless specified otherwise, this value is either
`0` (“Undefined”), `1` (“Allow”), `2` (“Deny”) or `3` (“Prompt the user”).
For storing arbitrary preferences per origin instead of just permission values,
the {searchfox}`content pref service <dom/interfaces/base/nsIContentPrefService2.idl>`
offers a good alternative to the permission manager.
The permission manager also supports {doc}`browser-scoped (per-tab) temporary
permissions <browser-scoped>` that are not stored to disk and are automatically
cleared when their tab is closed.
The {searchfox}`site permission manager <browser/modules/SitePermissions.sys.mjs>`
builds on top of both regular and browser-scoped permissions, and makes user
interfaces easier.
## Interfacing with the Permission Manager
The permission manager can be accessed through the `nsIPermissionManager`
interface. This interface is available through the
`@mozilla.org/permissionmanager;1` service, or through the quick
`Services.perms` getter in JavaScript. Below is a list of the most common
methods, and examples on how to use them with JavaScript. For a full list of
signatures, see {searchfox}`nsIPermissionManager.idl <netwerk/base/nsIPermissionManager.idl>`.
### `testExactPermissionFromPrincipal`
Returns any possible stored permission value for a given origin and permission
type. To also find permission values if the given origin is a subdomain of the
permission's origin, use the otherwise identical `testPermissionFromPrincipal`
method.
```js
// Only construct the principal yourself if you can't get from somewhere else
// (e.g. gBrowser.contentPrincipal) directly.
let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin(
);
let perm = Services.perms.testExactPermissionFromPrincipal(principal, "geo");
if (perm == Services.perms.ALLOW_ACTION) {
// Do things
}
```
### `addFromPrincipal`
Adds a permission to the permission manager for a given origin, permission type
and value. Optionally, the permission can be configured to expire after the
current browsing session ends, or to expire on a given UNIX timestamp in
milliseconds.
```js
let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin(
);
// Never expires
Services.perms.addFromPrincipal(principal, "geo", Services.perms.ALLOW_ACTION);
// Expires after the current session
Services.perms.addFromPrincipal(
principal,
"geo",
Services.perms.ALLOW_ACTION,
Services.perms.EXPIRE_SESSION
);
// Expires in 24 hours
Services.perms.addFromPrincipal(
principal,
"geo",
Services.perms.ALLOW_ACTION,
Services.perms.EXPIRE_TIME,
Date.now() + 1000 * 60 * 60 * 24
);
```
For per-tab temporary permissions, see {doc}`browser-scoped permissions
<browser-scoped>`.
### `removeFromPrincipal`
Removes a permission from the permission manager for a given origin and
permission type.
```js
let principal = Services.scriptSecurityManager.createContentPrincipalFromOrigin(
);
Services.perms.removeFromPrincipal(principal, "geo");
```