Chrome Extension Managed Storage — Best Practices

4 min read

Managed Storage Patterns for Enterprise Extensions

This document covers chrome.storage.managed for enterprise-managed extension settings in Chrome extensions.

Overview

Managed storage (chrome.storage.managed) provides a read-only storage area controlled by enterprise policies. IT administrators deploy settings organization-wide, and extensions receive pre-configured values they cannot modify.

Schema Definition

Define the managed storage schema in your extension’s manifest.json:

{
  "name": "My Extension",
  "manifest_version": 3,
  "storage": {
    "managed_schema": "managed-schema.json"
  }
}

The JSON schema file (managed-schema.json) defines acceptable values:

{
  "type": "object",
  "properties": {
    "apiEndpoint": {
      "type": "string",
      "description": "Pre-configured API endpoint for organization"
    },
    "enableFeatureX": {
      "type": "boolean",
      "description": "Enable Feature X for all users",
      "default": false
    },
    "maxRetries": {
      "type": "integer",
      "description": "Maximum retry attempts",
      "default": 3
    }
  }
}

Reading Managed Settings

Retrieve managed settings using chrome.storage.managed.get():

async function getManagedSettings() {
  const result = await chrome.storage.managed.get();
  return result;
}

// Usage
const settings = await getManagedSettings();
console.log(settings.apiEndpoint);

Detecting Managed vs Unmanaged Values

Check whether specific values are managed by verifying they exist in managed storage:

async function isValueManaged(key) {
  const managed = await chrome.storage.managed.get(key);
  return key in managed;
}

Layered Configuration Pattern

Implement layered configuration with priority: managed > sync > local:

async function getConfig() {
  const [managed, sync, local] = await Promise.all([
    chrome.storage.managed.get(),
    chrome.storage.sync.get(),
    chrome.storage.local.get()
  ]);

  return {
    apiEndpoint: managed.apiEndpoint || sync.apiEndpoint || 'https://default.example.com',
    enableFeatureX: managed.enableFeatureX ?? sync.enableFeatureX ?? false,
    maxRetries: managed.maxRetries ?? sync.maxRetries ?? 3,
    userPreferences: { ...local.userPreferences }
  };
}

Enterprise Policy Deployment

Admins deploy policies through Chrome Enterprise policies:

Windows: Registry at HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\ExtensionSettings\extension-id
macOS: com.google.Chrome plist
Linux: JSON in /etc/opt/chrome/policies/managed/

Example policy JSON:

{
  "apiEndpoint": "https://api.enterprise.example.com",
  "enableFeatureX": true,
  "maxRetries": 5
}

Managed-Aware Options Page

Display managed settings as locked/read-only:

async function renderOptionsPage() {
  const managed = await chrome.storage.managed.get();
  const userPrefs = await chrome.storage.sync.get();

  document.getElementById('apiEndpoint').value = managed.apiEndpoint || userPrefs.apiEndpoint || '';
  document.getElementById('apiEndpoint').disabled = 'apiEndpoint' in managed;

  document.getElementById('enableFeatureX').checked = managed.enableFeatureX ?? userPrefs.enableFeatureX ?? false;
  document.getElementById('enableFeatureX').disabled = 'enableFeatureX' in managed;
}

Listening for Admin Updates

Use onChanged to detect when administrators update policies:

chrome.storage.onChanged.addListener((changes, areaName) => {
  if (areaName === 'managed') {
    console.log('Admin updated managed settings:', changes);
    // Refresh configuration, notify user, etc.
  }
});

Testing Managed Storage

Enable managed storage testing in Chrome:

Navigate to chrome://flags/#managed-storage
Enable the flag
Use --managed-storage-override-dir flag to load test policies

Documentation for Admins

Provide admins with a policy template explaining available settings, types, and descriptions.