> For the complete documentation index, see [llms.txt](https://docs.avanoo.ai/public-knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avanoo.ai/public-knowledge-base/browsers-extensions.md).

# Browsers Extensions

## Avanoo Usage Modes

### What is this?

Avanoo is a tool that helps organisations optimise their tech stacks. We let your IT administrator see which Software-as-a-Service (SaaS) applications are being used so that your organisation can cut unused licenses, identify security vulnerabilities, and find tools that are better suited to its needs.

Avanoo was designed with privacy in mind. Depending on how much you want Avanoo to know about individual employees, it can run in one of two usage modes: **Pseudonymous** and **Identified**. These modes sit on a spectrum — from maximum employee privacy to the richest per-user analytics — and you can choose the one that best matches your organisation's needs.

This document explains what each mode means, what it can and cannot do, and how to deploy it.

### How does it work?

Every activity Avanoo collects has to be attributed to *something*. The usage mode determines what that "something" is:

* In **Pseudonymous** mode, activity is attributed to an aliased identity that you control. Avanoo can group activity and reconcile it across devices, but it never learns the real identity behind the alias.
* In **Identified** mode, activity is attributed to a real user identity from your directory. Avanoo can show named users, real groups, and full per-user visibility.

What this means in practice — per-user tracking, grouping into teams or segments, reconciling one person's activity across multiple browsers and devices, and the ability to display nudges — depends on the mode you choose.

#### At a glance

* **Pseudonymous**
  * Identity Avanoo holds: an aliased (fake) email you control.
  * Per-user tracking: accurate, per aliased user.
  * Groups / segments: available.
  * Multi-browser reconciliation: available.
  * Nudging: available.
  * Privacy level: high — Avanoo never sees real identities.
* **Identified**
  * Identity Avanoo holds: the real user identity.
  * Per-user tracking: accurate, per real user.
  * Groups / segments: available (real groups).
  * Multi-browser reconciliation: available.
  * Nudging: available.
  * Privacy level: standard — real names are visible.

***

### 1. Pseudonymous

In Pseudonymous mode, you give Avanoo a list of users with their email addresses and groups — but the email addresses are deliberately fake (aliased). You then deploy these fake emails to your fleet through your MDM, writing each user's alias into the registry of their device. The Avanoo extension reads that alias and identifies the browser with it.

This gives you the best of both worlds: Avanoo is never aware of the real identity of any user, yet the tracking is accurate, the groups are correct, and activity is reconciled across multiple browsers and devices for the same aliased identity. Nudging is fully available.

**Best for:** organisations that want accurate per-user and per-group analytics plus cross-device reconciliation, while keeping employees' real identities private.

#### Generating the alias (important)

The username part of the alias must be a one-way hash of the user's real identity — never the real identity itself, and never a value Avanoo could reverse. This is what makes Pseudonymous mode private: Avanoo only ever sees an opaque token like `alias-7f3a`, with no way to recover the person behind it.

Hashing the real identity (for example the user's directory `objectGUID`, UPN, or email) gives you two properties at once:

* **Stable per person.** The same input always produces the same alias, so a user's activity is correctly reconciled across every browser and device they use.
* **Irreversible for Avanoo.** Because we only receive the hash, your employees' real identities stay entirely on your side.

Generate the alias the same way everywhere (same hash function and, ideally, a private salt you keep) so the value is consistent across devices and across MDM runs. Keep your own mapping of alias → real person if you ever need to reverse it — Avanoo never receives that mapping. The examples below show how to derive the alias from the signed-in user with SHA-256.

#### Encoding tags and groups in the alias

You can attach a user's tags or groups directly to their fake email by appending them to the alias, following these rules:

* Use `___` (a triple underscore) to separate the username from the tags.
* Use `__` (a double underscore) to separate each tag from the next.
* Use `_` (a single underscore) anywhere a tag contains a space — single underscores are converted to spaces.

For example:

```
alias-7f3a___france__it_metier@yourcompany.example
```

Avanoo reads this as:

* **Username (alias):** `alias-7f3a` (a one-way hash of the real user identity)
* **Tags:** `france` and `it metier` (the `_` in `it_metier` becomes a space)

Avanoo files the aliased identity under those tags, with no separate import needed for that mapping.

This is optional and complementary to sending a user/group list: if you embed the tags in the alias, they are derived automatically from the email; if you prefer, you can omit them and send the user-to-group mapping through the Avanoo app chat instead. Either way, the real identity behind the alias is never revealed to Avanoo.

#### Deploying Pseudonymous via MDM

1. **Prepare your user list.** Build a list of users with a fake (aliased) email for each one and the group they belong to. Generate each alias as a one-way hash of the user's real identity (see "Generating the alias" above) so it is stable per person and irreversible for Avanoo. You can either keep the groups separate or encode them directly into the alias (`___` between the username and the tags, `__` between each tag, `_` for a space — for example `alias-7f3a___france__it_metier@yourcompany.example` → user `alias-7f3a`, tags "france" and "it metier"). Keep your own mapping of alias to real person — Avanoo never receives it.
2. **Import the list into Avanoo.** Send us the list of aliased users and their groups through the Avanoo app chat so we can create them and their groups on our end. (If you encode tags in the alias, they are created automatically from the email.)
3. **Push the alias to each device via MDM.** Using your MDM solution, set the Avanoo extension's managed `userEmail` policy on each device to that user's fake email — including any encoded tags, if you use that convention. The extension reads this value from enterprise managed storage during its background identification check.
4. **Let the extension reconcile automatically.** When the extension reads the managed `userEmail`, it registers the browser under that fake email. Avanoo then reconciles the browser's activity to the matching aliased user — including activity from any other browser or device carrying the same alias — and assigns it to the encoded tags. If the managed email later changes, the extension automatically moves the browser to the new identity (and tags).

The extension reads a single managed-storage value, `userEmail`, set by your MDM policy. Below are examples of how to deliver it.

**Windows example (Chrome + Edge)**

On Windows, Chromium browsers read extension policies from the registry under each extension's `3rdparty\Extensions\<EXTENSION_ID>\policy` key. Because each user has their own alias, write the policy under `HKCU` (the per-user hive) rather than `HKLM` (machine-wide), so the value follows the signed-in user. Replace `EXTENSION_ID` with your organisation's Avanoo extension ID (we provide it with your deployment) and set `userEmail` to the user's fake email:

```powershell
# alias-7f3a is a one-way hash of the real identity (see "Generating the alias" above).
# alias-7f3a___paris__product_manager -> user "alias-7f3a", tags "paris" and "product manager"
$userEmail = "alias-7f3a___paris__product_manager@yourcompany.example"
$extensionId = "YOUR_AVANOO_EXTENSION_ID"

$browsers = @(
    @{ Name = "Chrome"; Vendor = "Google" },
    @{ Name = "Edge";   Vendor = "Microsoft" }
)

foreach ($browser in $browsers) {
    $policyPath = "HKCU:\Software\Policies\$($browser.Vendor)\$($browser.Name)\3rdparty\Extensions\$extensionId\policy"

    if (-not (Test-Path $policyPath)) {
        New-Item -Path $policyPath -Force | Out-Null
    }

    # The Avanoo extension reads this managed value as the user's identity
    New-ItemProperty -Path $policyPath -Name "userEmail" `
        -PropertyType String -Value $userEmail -Force | Out-Null
}
```

The `...\Software\Policies` key is writable only by `Administrators`/`SYSTEM`, so this must run from an elevated context (your MDM, or a script running as `SYSTEM`). Note that when a script runs as `SYSTEM`, `HKCU` resolves to the SYSTEM hive rather than the user's — so either deliver the value as a **user-scoped Group Policy Preference** (the Group Policy engine runs as `SYSTEM` and writes each user's own `HKCU` for you) or, from a `SYSTEM` script, target the user's hive explicitly via `HKEY_USERS\<SID>\Software\Policies\...`. For Brave, use the vendor/browser path `BraveSoftware\Brave`.

Instead of hardcoding the tags, you can read the user's location, job title, or group from Active Directory and build the suffix automatically (`___` before the tags, `__` between them, `_` for spaces):

```powershell
$sam = (Get-CimInstance Win32_ComputerSystem).UserName.Split('\')[-1]

# Look up the attributes you want to encode (adjust the names to your AD schema).
$searcher = New-Object System.DirectoryServices.DirectorySearcher
$searcher.Filter = "(&(objectClass=user)(sAMAccountName=$sam))"
$u = $searcher.FindOne().Properties

$location = [string]$u["physicaldeliveryofficename"]   # location, e.g. "Paris"
$job      = [string]$u["title"]                         # job title, e.g. "Product Manager"
$group    = [string]$u["department"]                    # group/team, e.g. "Sales"

# Lowercase + turn spaces into "_", then join the tags with "__" after a "___".
$tags = @($location, $job, $group) |
    Where-Object { $_ } |
    ForEach-Object { ($_.Trim().ToLower() -replace "[^a-z0-9]+", "_").Trim("_") }

# Derive the username as a one-way SHA-256 hash of the real identity (here the
# sAMAccountName) — opaque to Avanoo, but stable for the same person on every device.
$bytes = [Text.Encoding]::UTF8.GetBytes($sam.ToLower())
$hash  = ([BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash($bytes)) -replace "-", "").Substring(0, 8).ToLower()
$alias = "alias-$hash"

$userEmail = "${alias}___" + ($tags -join "__") + "@yourcompany.example"
```

**macOS example**

On macOS, deliver the same `userEmail` value (e.g. `alias-7f3a___paris__product_manager@yourcompany.example`) as a managed app configuration (a managed preferences profile for the Avanoo extension) through your MDM. The extension reads it from the same managed storage as on Windows.

When your Macs are directory-bound, you can read the same attributes with `dscl` and build the suffix the same way:

```bash
consoleUser=$(/usr/bin/stat -f%Su /dev/console)

location=$(/usr/bin/dscl . -read "/Users/$consoleUser" PhysicalDeliveryOfficeName 2>/dev/null | sed 's/^[^:]*: *//')  # e.g. "Paris"
job=$(/usr/bin/dscl . -read "/Users/$consoleUser" JobTitle 2>/dev/null | sed 's/^[^:]*: *//')                        # e.g. "Product Manager"

# Lowercase + spaces -> "_", tags joined by "__" after a "___".
to_tag() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/_/g; s/^_+|_+$//g'; }

# Derive the username as a one-way SHA-256 hash of the real identity (here the
# console user) — opaque to Avanoo, but stable for the same person on every device.
aliasId=$(printf '%s' "$consoleUser" | tr '[:upper:]' '[:lower:]' | shasum -a 256 | cut -c1-8)

userEmail="alias-${aliasId}___$(to_tag "$location")__$(to_tag "$job")@yourcompany.example"
```

> Note: Managed storage is not supported on Safari, so Pseudonymous identification via MDM applies to Chromium browsers (Chrome, Edge, Brave) and Firefox.

***

### 2. Identified

Identified mode is the classic setup. Real user identities come from your identity provider or directory (or a CSV import), and the extension identifies browsers with real email addresses.

This unlocks Avanoo's full capability: per-user tracking under real names, real groups from your directory, reconciliation across multiple browsers and devices, nudging, and the ability to join usage data with your directory information.

**Best for:** organisations that already manage identities centrally and want full, named visibility.

#### Ways to deploy Identified

You can identify browsers in Identified mode in several ways:

* **Automatic detection** — the extension detects the signed-in user's email from the browser profile, the corporate mailbox, or an SSO/OIDC session, with no configuration required.
* **Directory / CSV import** — you provide the user and group list to Avanoo and identities are matched as devices report in.
* **GPO push** (below) — you set each user's real email as a managed policy value through Group Policy, with no script.

#### Deploying Identified via GPO (no script)

Because Identified pushes the user's **real** email — not a computed hash — you don't need any script: a Group Policy Preference can deliver the value directly. The Group Policy engine runs as `SYSTEM`, so it writes the protected `...\Software\Policies` key into **each user's own `HKCU`** automatically. That means it handles the permissions for you and gives every signed-in user their own identity, so shared machines work with no extra effort.

The extension reads a single managed-storage value, `userEmail`. Which route you take depends only on whether the email can be derived from the Windows sign-in name.

**Prerequisite:** the device must be **domain-joined** — Chrome and Edge only load registry-based policies on AD-enrolled machines (which is inherently the case when you apply a GPO).

**Case 1 — email is `sAMAccountName@yourdomain` (one item covers everyone)**

A single Group Policy Preference, resolved per user at logon:

1. In the **Group Policy Management Console**, edit a GPO linked to your users' OU.
2. Go to **User Configuration → Preferences → Windows Settings → Registry → New → Registry Item** and set:
   * **Action:** `Update`
   * **Hive:** `HKEY_CURRENT_USER`
   * **Key Path:** `Software\Policies\Google\Chrome\3rdparty\extensions\<EXTENSION_ID>\policy`
   * **Value name:** `userEmail`
   * **Value type:** `REG_SZ`
   * **Value data:** `%LogonUser%@yourcompany.example` (press F3 to insert `%LogonUser%`; it resolves to each user's sign-in name)
3. Add a second item for **Edge** with the key path `Software\Policies\Microsoft\Edge\3rdparty\extensions\<EXTENSION_ID>\policy`.

That's it — no script, and each user gets their own real email.

**Case 2 — email is not derivable from the sign-in name**

If your emails don't match the sign-in name (e.g. `jdupont` but `jean.dupont@yourcompany.example`), `%LogonUser%` can't reconstruct the address and Group Policy Preferences cannot read the AD `mail` attribute. Two options, both still driven by GPO:

* **Item-level targeting** — create one Registry item per user with the literal email, targeted to that user (Registry item → **Common** tab → **Item-level targeting**). No client-side script; you just maintain the list, typically generated once from a directory export.
* **`SYSTEM` logon helper** — deploy a scheduled task (via GPO, run as `SYSTEM`, triggered at logon) that reads the signed-in user's `mail` from Active Directory and writes it to `HKEY_USERS\<SID>\Software\Policies\...\policy`.

**macOS**

GPO is Windows-only. On macOS, deliver the same `userEmail` value (the user's real email) as a managed app configuration — a managed preferences profile for the Avanoo extension — through your MDM.

**Verify**

On a client, run `gpupdate /force`, sign out and back in, then open `chrome://policy` (or `edge://policy`) and click **Reload policies** — the Avanoo extension and its `userEmail` value should appear.

> Note: On a shared machine, the per-user `HKCU` policy above gives each signed-in user their own identity; a machine-wide `HKLM` value would attribute every user on the device to a single identity. Managed storage is not supported on Safari, so Identified applies to Chromium browsers (Chrome, Edge, Brave) and Firefox.

***

### Which mode should I choose?

The two modes form a spectrum that trades employee privacy against analytics depth:

* **Identified** is the least private and the most granular: full named visibility, real groups, and reconciliation across devices.
* **Pseudonymous** is the middle ground: it preserves accurate per-user analytics, correct groups, and cross-device reconciliation, all without ever revealing real identities to Avanoo.

If you're unsure which mode fits your organisation, reach out to us through the Avanoo app chat and we'll help you decide.