> ## 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.                                                                                       |
| `managedUserEmail`             | string (email)                    | The email address of the person using this specific device or browser profile. Used to attribute Shadow AI traffic-monitoring events to a person when no one is signed into the extension. Requires `provisioningApiKey` to also be set — see [Per-User Attribution for Shadow AI Events](#per-user-attribution-for-shadow-ai-events) below. |
| `suppressLoginPromptOnInstall` | boolean                           | Prevents the Sign-In popup and the first-run "Welcome to Airia" tab from automatically opening when the extension is installed or started. Intended for silent/bulk deployments where these prompts would be disruptive. Users can still sign in manually via the toolbar icon. Defaults to `false`.                                         |

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`.

<Note>
  Unlike the other fields on this page, `managedUserEmail` is **per-user, not per-organization** — it identifies one specific person, so it must be pushed through a policy scoped to the individual user or device, not the same org-wide value you'd use for `region`, `customAppUrl`, or `provisioningApiKey`. Consult your MDM tool's documentation for how to vary a managed policy value per user or device (for example, Chrome Enterprise supports this via user-level policies rather than device-level policies).
</Note>

<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>

### Per-user attribution for Shadow AI events

Attributes Shadow AI traffic-monitoring events to a specific person, even when they haven't signed into the extension. Requires `provisioningApiKey` (for authentication) plus `managedUserEmail`, pushed via a **user-scoped** policy so each person's device gets their own email value rather than one shared org-wide value.

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

If the email matches a real Airia platform account in your tenant, events are attributed to that person directly. If it doesn't match any account, events are still recorded, tagged with the email as an unresolved identity. Without `managedUserEmail`, events captured while no one is signed in are dropped rather than recorded.

### Silent installation for bulk/MDM rollout

Suppresses the Sign-In popup and the first-run "Welcome to Airia" tab so a silent, background-pushed install doesn't interrupt the end user. Commonly paired with `provisioningApiKey` for a fully zero-touch rollout, but works on its own too — the user just won't be automatically prompted to sign in on their own.

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

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
4. If `suppressLoginPromptOnInstall` is set, no Sign-In popup or "Welcome to Airia" tab should open automatically — clicking the toolbar icon still opens the popup for manual sign-in

`managedUserEmail` has no visible effect in the extension UI — it only affects how Shadow AI traffic-monitoring events are attributed in the background when no one is signed in. Verify it's working by checking your Shadow AI event reports for activity attributed to the configured email from a signed-out device.

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` and `managedUserEmail` for both authentication and event attribution
  </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>

  <Accordion title="Shadow AI events aren't attributed to a specific user when no one is signed in">
    * Confirm both `managedUserEmail` **and** `provisioningApiKey` are set — `managedUserEmail` alone can't authenticate the request, so events are dropped without a provisioning key
    * Confirm `managedUserEmail` is being pushed as a per-user policy value, not a single value shared across your whole organization — every signed-out user attributed by email needs their own value
    * If events are attributed to the raw email rather than a named person in your reports, no platform account matches that email in this tenant — the event is still recorded, just not linked to an existing user
  </Accordion>

  <Accordion title="The Sign-In popup or Welcome tab still appears even with suppressLoginPromptOnInstall set">
    * Confirm the value is `true` (not just present) in the managed policy, and that the policy has synced — check `chrome://policy` or Firefox's `about:policies` on an affected machine
    * This flag only suppresses the *automatic* prompts shown on install/startup — a user clicking the toolbar icon to sign in manually will always see the popup, by design
    * If a user has already completed first-time sign-in before the policy was applied, they won't see the "Welcome to Airia" tab again regardless of this setting, since it only fires once per install
  </Accordion>
</AccordionGroup>