12.1 Agents → Setup

Agents → Setup is where you get everything a client needs. It shows the install commands with the server address already filled in, builds the enterprise installers, reveals the agent token, offers the manual downloads, and manages the Microsoft 365 add-in key. The server address comes from the host name in the console URL, so open the console by its DNS name (for example ada.example.com), not by IP. An IP ends up in the generated commands and manifests, and TLS name validation then fails on the clients.

The page is a single column of cards. The Client setup help box at the top summarises the flow. The cards, in order:

12.1.1 Windows client (administrator PowerShell)

The card shows a command like this:

curl.exe -k https://ada.example.com/windows-client-setup.ps1 -o "$env:TEMP\ada-setup.ps1"
Set-ExecutionPolicy -Scope Process Bypass -Force
$t = (New-TemporaryFile).FullName; Set-Content -LiteralPath $t -Value '<TOKEN>' -NoNewline
& "$env:TEMP\ada-setup.ps1" -Server ada.example.com -WithAgent -WithEnforcement -IngestTokenFile $t; Remove-Item -LiteralPath $t

Until you click Reveal or Copy, the token appears as <TOKEN — filled in by Reveal / Copy>. Copy fetches the real token from the server, puts the complete command on the clipboard, and writes a setup_token_viewed audit record. Paste the command into an elevated PowerShell window.

The token is passed in a private temporary file, never on the command line. Any local user can read process command lines, and deployment tools log them.

For a basic install without file monitoring or Office enforcement, remove -WithAgent and -WithEnforcement.

12.1.2 Enterprise deployment (SCCM / Intune / GPO)

This card builds per-installation installers. A generic installer ships with each release. When you click the button, the server packages it with a configuration file holding this server’s live values.

The Windows .adacfg carries: - the server address - the root CA - the policy-signing public key - the agent token - the Office manifests

So a Windows client does not need to reach the server while installing.

The macOS .adacfg carries: - the server address - the token - the signing key

The macOS package then downloads the agent from the server, so a Mac must reach the server while installing.

Each download: - is limited to administrators - is never cached (Cache-Control: no-store) - writes an installer_created audit record with the SHA-256 values

After a build the card shows three SHA-256 values:

Procedure (Windows, SCCM / Intune / GPO): 1. Click Create installer (Windows) and save the zip. 2. Verify the SHA-256 against the value shown on the card. 3. Extract both files into the same folder. Do not rename AdaAgentSetup.adacfg. The installer reads it from its own folder. If it is missing, the installer stops with “Configuration file NOT found next to the installer” instead of installing against the wrong server. 4. Package the folder: - Intune: a Win32 app (.intunewin of the folder). - SCCM: an application with the folder as content. - GPO: a computer startup script.

All three run as SYSTEM. 5. Install command: AdaAgentSetup-<version>.exe /S. 6. Detection rule: - Registry key HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\AdaClassification, value DisplayVersion, 64-bit view. - If some machines were installed or upgraded with the PowerShell script (which writes no Add/Remove Programs entry), detect on the file version of C:\Program Files\AdaClassification\service\Ada Agent Service.exe instead. 7. Return codes: map 1618 to Retry (it is the Windows “fast retry” code).

Installer command-line switches:

12.1.3 macOS client (Terminal)

The card shows:

t=$(mktemp) && printf '%s' '<TOKEN>' > "$t"
curl -sk https://ada.example.com/macos-client-setup.sh | sudo INGEST_TOKEN_FILE="$t" bash -s -- ada.example.com --with-agent; rm -f "$t"

Run it in Terminal as the user who will use the Mac (it uses sudo). Do not run it from a root shell. If setup cannot determine the real console user, it stops.

12.1.4 Agent authentication

The card explains the token and shows it masked. Click: - Reveal to show it. - Hide to mask it again. - Copy to put it on the clipboard.

The first Reveal or Copy in a page visit downloads the real value and writes setup_token_viewed (who and from which IP; the token value is never logged).

How the token is used: - It is an enrolment token. A new agent uses it once to enrol. The agent then generates its own key pair, receives a one-year certificate, and signs every later request with its own key (section 13.3.9). - After enrolment it is used only for re-enrolment and diagnostics upload. - Rotation is a server-side action: bash deploy/rotate-ingest-token.sh --grace 14. During the grace window the card shows “A previous token is still accepted until …”. - Rotation affects new installs only. Agents that have already enrolled keep working. - If agents that never enrolled exist, the card says so. These are pre-1.2 agents that cannot connect to this server; upgrade them.

12.1.5 Next steps (on the client)

1. Close all Office applications completely and reopen them.
2. The COM add-ins and enforcement load automatically when Word, Excel or Outlook opens, if the module is enabled in policy.
3. The web panel needs a one-time add per user per app: Add-ins → More Add-ins → My Add-ins | Shared Folder → Ada Data Classification → Add. After that it stays on the ribbon permanently.
4. For Outlook on the web, sideload manually via aka.ms/olksideload (testing only; use central deployment in production).

12.1.6 Downloads

Export with a different address. The manifests contain the server’s own address. If clients reach the server under another name (public FQDN, load balancer, NAT), type that address here: a host name or IP with an optional :port, and no scheme or path. Invalid input shows “Enter a hostname or IP (an optional :port is allowed) — no scheme, no path.” When the input is valid, download links appear for Word, Excel, PowerPoint, Outlook (Exchange Online) and Outlook (on-prem Exchange). Every URL inside the manifest is rewritten (task pane, commands, icons, AppDomain). Nothing on the server changes.

12.1.7 Production: M365 Centralized Deployment

If you have a Microsoft 365 tenant, this is the recommended route for the web add-ins. No catalog share, certificate or client script is needed.

1. Open the Microsoft 365 admin center → Settings → Integrated apps → Upload custom apps.
2. Upload the keyed manifest from the next card (recommended). Alternatively, give the plain manifest URL shown on the card:
   • https://ada.example.com/manifest-word.xml
   • https://ada.example.com/manifest-excel.xml
   • https://ada.example.com/manifest-ppt.xml
   • https://ada.example.com/manifest-outlook.xml
3. Assign the users or groups. Office pushes the add-ins to them. Microsoft’s propagation can take up to 24 hours.

12.1.8 Microsoft 365 add-in key

Add-ins deployed from Microsoft 365 or an Exchange organization share one manifest for all users. That manifest cannot carry a machine’s panel token. The Microsoft 365 add-in key goes into the manifest’s URL path instead. With it, the server trusts the add-in: - Outlook on the web gets the policy group that matches the user’s mail address. - The add-in receives the full content rules.

Without it, the add-in is treated as an anonymous caller. Anyone who can open the manifest can read the key, but it exposes nothing beyond what the add-in already receives.

Card states and buttons:

Procedure: 1. Click Generate key (or Rotate key). 2. Download the keyed manifest for each app you deploy. 3. In the Microsoft 365 admin center, Settings → Integrated apps, upload the file as an update of the existing Ada app. For a single mailbox, you can instead remove the add-in in Outlook and add the file again. 4. After a rotation, repeat step 3 within the 7-day window.

12.1.9 No Microsoft 365? Outlook send protection still works

Send-time enforcement in the web add-in needs the right Outlook event for your mail server. Microsoft 365 is not required. Deploy exactly one Outlook manifest per mailbox:

On-premises deployment from the Exchange Management Shell:

$Data = Get-Content -Path '.\manifest-outlook-onprem.xml' -Encoding Byte -ReadCount 0
New-App -OrganizationApp -FileData $Data -DefaultStateForUser Enabled

Hardening: - Macs: defaults write com.microsoft.outlook OnSendAddinsWaitForLoad -bool true (push with Jamf or Intune). - On-premises OWA: runs ItemSend handlers only when the mailbox policy allows it: Set-OwaMailboxPolicy <policy> -OnSendAddinsEnabled $true.