> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Extension MDM Deployment Guide

> Deploy and pre-configure the Airia browser extension across your organization using MDM/managed storage policies.

The Airia browser extension supports centralized configuration through each browser's managed storage / enterprise policy system. This lets you push a pre-configured, optionally locked connection to every user's browser without any manual setup — commonly deployed through tools like Google Admin Console, Microsoft Intune, or Group Policy.

For an overview of what this enables, see [Browser Extension Configuration](/building-and-deploying-agents/interface-options/browser-extension#enterprise-deployment).

## Configuration Schema

The extension reads its enterprise configuration from a managed storage object with the following fields:

| Field                | Type                              | Description                                                                                                                                                                                                                                            |
| -------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `region`             | string (`na`, `eu`, `au`, `mena`) | Pre-defined Airia authentication region for the organization                                                                                                                                                                                           |
| `customAppUrl`       | string (URL)                      | **Recommended.** Your organization's Airia app URL (e.g., `https://app.company.com`). The extension automatically discovers the correct API and auth endpoints via `.well-known/service-configuration` — no need to configure them separately.         |
| `customApiHost`      | string (hostname)                 | **Deprecated** — use `customAppUrl` instead. Custom API server hostname.                                                                                                                                                                               |
| `customAuthHost`     | string (hostname)                 | **Deprecated** — use `customAppUrl` instead. Custom authentication server hostname.                                                                                                                                                                    |
| `lockConfiguration`  | boolean                           | Prevents users from changing region or server settings in the extension UI. Defaults to `false`.                                                                                                                                                       |
| `provisioningApiKey` | string                            | A tenant API key that lets the extension fetch deployments and policies without requiring the user to sign in — enables zero-touch rollout. If a user does sign in with their own account, their credentials take precedence over the provisioned key. |

To identify your Airia instance, configure **one** of: `region`, `customAppUrl`, or the `customApiHost` + `customAuthHost` pair. `provisioningApiKey` can be combined with any of these — it controls authentication, not the instance. If you configure `provisioningApiKey` alone with none of the above, the extension falls back to the default (`na`) region, so it's best paired with an explicit region or `customAppUrl`.

<Tip>
  Use `customAppUrl` for new deployments. `customApiHost`/`customAuthHost` remain supported for existing configurations but won't pick up future service endpoints automatically.
</Tip>

## Deploying on Chrome and Edge

Chrome and Edge (Chromium) read extension managed storage from the `3rdparty.extensions.<extension-id>` policy key.

### Option A: Google Admin Console (Chrome Browser Cloud Management)

1. Sign in to the [Google Admin Console](https://admin.google.com)
2. Navigate to **Devices → Chrome → Apps & Extensions**
3. Select the organizational unit to configure
4. Find or add the Airia extension by ID
5. Open its **Policy for extensions** field and paste your configuration JSON (see examples below)
6. Save — the policy syncs to managed Chrome browsers on their next policy refresh

### Option B: Group Policy (GPO) / Intune ADMX

1. Install the [Chrome ADMX templates](https://chromeenterprise.google/browser/download/) (or the Edge equivalent) on your management workstation
2. Under **Computer Configuration → Administrative Templates → Google Chrome / Microsoft Edge → Extensions**, configure **Extension management settings**, or use the dedicated **3rd party extension management** policy
3. Add an entry for the Airia extension ID with a `"policy"` block containing your configuration JSON
4. Deploy via GPO or an Intune configuration profile targeting your managed devices

## Deploying on Firefox

Firefox reads managed configuration from `policies.json`'s `3rdparty.Extensions.<extension-id>` block.

1. Generate or hand-edit a `policies.json` using the [Enterprise Policy Generator](https://github.com/mozilla/policy-templates) extension, or your existing Firefox ADMX/Intune policy deployment
2. Add a `3rdparty` → `Extensions` → `<extension-id>` entry containing your configuration JSON
3. Deploy `policies.json` to the appropriate `distribution/` or platform-specific policy location on managed machines, or push via GPO/Intune ADMX for Firefox

## Worked Examples

### Pre-defined region

```json theme={null}
{
  "region": "eu",
  "lockConfiguration": true
}
```

### Custom app URL (recommended)

```json theme={null}
{
  "customAppUrl": "https://app.company.com",
  "lockConfiguration": true
}
```

### Legacy custom hosts

```json theme={null}
{
  "customApiHost": "api.company.com",
  "customAuthHost": "auth.company.com",
  "lockConfiguration": true
}
```

### Zero-touch provisioning

Pre-authenticates the extension using a tenant API key, so users never have to sign in manually. Any user who does sign in with their own credentials will use those instead.

```json theme={null}
{
  "customAppUrl": "https://app.company.com",
  "provisioningApiKey": "<tenant-api-key>",
  "lockConfiguration": true
}
```

<Warning>
  Treat `provisioningApiKey` as a secret. Anyone with access to the managed policy value can use it to fetch your tenant's deployments and policies.
</Warning>

Each of the above JSON objects is the *value* of the extension's managed storage — wrap it in the policy envelope your management tool expects (e.g., nested under the extension ID for Chrome/Edge's `3rdparty.extensions` or Firefox's `3rdparty.Extensions`).

## Verifying Deployment

Once policy has synced to a managed browser:

1. Install or open the Airia extension
2. Click the extension icon — if `lockConfiguration` is set, you'll see a locked configuration screen showing the organization's region or app URL, with no ability to change it
3. If `provisioningApiKey` is set, the extension will connect and fetch deployments automatically without prompting for sign-in

See [Locked Configuration](/airia-chat/browser-extension/getting-started#locked-configuration) for what end users see once MDM configuration is applied.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The extension doesn't pick up the managed configuration">
    * Confirm the extension ID in your policy matches the installed extension's ID exactly
    * Managed storage policies typically require a browser restart or a policy refresh (`chrome://policy` → **Reload policies** on Chrome/Edge) to take effect
    * Confirm the policy was actually pushed to the target organizational unit or device group
  </Accordion>

  <Accordion title="Which fields take precedence if I configure more than one?">
    * `customAppUrl` takes precedence over `region` and over `customApiHost`/`customAuthHost` if multiple are present
    * `provisioningApiKey` operates independently — it controls authentication, not which Airia instance the extension talks to
    * A signed-in user's own credentials always take precedence over `provisioningApiKey`
  </Accordion>

  <Accordion title="Users can still change the region or server settings">
    Verify `lockConfiguration` is set to `true` (not just present) in the managed policy value, and that the policy has synced — check `chrome://policy` or Firefox's `about:policies` on an affected machine to confirm the value the browser actually received.
  </Accordion>
</AccordionGroup>