Document Index: IT Setup

Run one shared document index for your company on your own Windows server. People sign in with their Windows login or Microsoft Entra ID, access is by group, and the documents never pass through SphereHarness.

Which sign-in

1. Install the service on a Windows server

The service is CADCoPilot.Rag.Server.exe. Any SphereHarness add-in installer puts it in %ProgramFiles%\SphereHarness\Rag\ with the Document indexing service feature, together with its embedding model. It needs the ASP.NET Core 8 Runtime (x64).

Create a folder for the index (e.g. C:\ProgramData\SphereHarness\Rag) that the service account can write, and put the settings in appsettings.Production.json beside the exe — the installer never overwrites that file:

{
  "Rag": {
    "ConnectionString": "Data Source=C:\\ProgramData\\SphereHarness\\Rag\\index.db",
    "Auth": {
      "Mode": "Windows",
      "TenantId": "org",
      "AllowedGroups": [ "CORP\\CAD-Document-Readers" ],
      "WriterGroups": [ "CORP\\CAD-Document-Editors" ]
    }
  },
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://0.0.0.0:8644",
        "Certificate": { "Subject": "docindex.corp.example", "Store": "My", "Location": "LocalMachine" }
      }
    }
  }
}

Then, in an elevated prompt:

sc.exe create SphereHarnessDocIndex binPath= "\"C:\Program Files\SphereHarness\Rag\CADCoPilot.Rag.Server.exe\"" start= auto obj= "CORP\svc-docindex" password= ********
sc.exe start SphereHarnessDocIndex
netsh advfirewall firewall add rule name="SphereHarness document index" dir=in action=allow protocol=TCP localport=8644

obj= is optional (without it the service runs as LocalSystem). https://docindex.corp.example:8644/v1/health answers {"status":"ok"} without signing in — use it for monitoring.

2. The certificate

Issue a certificate from your internal CA whose subject or SAN is the name people will type, import it into Local Computer → Personal, and let the service account read its private key. Kestrel picks it up by subject as above. Plain http:// works on a trusted network but sends documents unencrypted.

3. Windows authentication and AD groups

"Mode": "Windows" makes the service itself accept the caller's Windows login — no IIS needed. Every request except /v1/health must be signed in:

• Not signed in → 401 with a Negotiate challenge.
• AllowedGroups → may search and list. Entries are DOMAIN\Group names or SIDs.
• WriterGroups → may also upload and delete. A writer is also a reader.
• Signed in, in neither → 403. If both lists are empty nobody gets in, and the service says so in its log at start.

The service holds one tenant (TenantId): everyone who may use this server searches the same documents. Run a second service on another port for a second, separate collection.

Kerberos: if the service runs as a domain account and people reach it by a DNS name, register the SPN once: setspn -S HTTP/docindex.corp.example CORP\svc-docindex. Without it Windows falls back to NTLM, which works unless your domain has disabled NTLM. Windows authentication is kept on HTTP/1.1 automatically.

IIS instead of Kestrel (optional): host the same folder in IIS with the ASP.NET Core Module and enable both Windows Authentication and Anonymous Authentication (the service issues the challenge itself, and /v1/health stays open). Keep "Mode": "Windows". Kestrel as a Windows service is the tested setup.

4. Microsoft Entra ID

For an index in your cloud. SphereHarness registers nothing; you create one app registration in your tenant:

1. App registrations → New registration, e.g. “SphereHarness Document Index”, single tenant.
2. Expose an API → set the Application ID URI (api://<application id>) and add a scope such as access_as_user.
3. App roles → create Documents.Read and Documents.Write for Users/Groups.
4. Authentication → Add a platform → Mobile and desktop applications → redirect URI http://localhost. There is no client secret: the desktop agent signs in in the browser.
5. API permissions → Add a permission → My APIs → the same app → access_as_user, then Grant admin consent.
6. Enterprise applications → the same app → Users and groups → assign your groups to Documents.Read or Documents.Write.

The service settings:

"Auth": {
  "Mode": "Entra",
  "AllowedGroups": [ "Documents.Read" ],
  "WriterGroups": [ "Documents.Write" ],
  "Entra": { "TenantId": "<directory (tenant) id>", "Audience": "<application (client) id>" }
}

The service accepts only tokens issued by your tenant (v1 and v2 issuers), for your application (<id> or api://<id>), signed with your tenant's published keys and not expired. The groups lists match the token's roles (app roles) or groups (group object ids). People's agents ask for api://<application id>/.default unless you set a scope, and keep the sign-in for their Windows account only, encrypted with DPAPI.

5. Tell every PC where the index is

Three layers, highest first. A person's own setting wins only where the layer above allows it and they chose to.

Machine policy (GPO or installer) — no server involved

HKLM\Software\Policies\SphereHarness\DocumentIndex, REG_SZ values:

Push it with Group Policy Preferences (Computer Configuration → Preferences → Windows Settings → Registry), or at install time with the MSI properties DOCINDEX_URL, DOCINDEX_MODE, DOCINDEX_AUTH, DOCINDEX_TENANT, DOCINDEX_ENTRA_TENANT, DOCINDEX_ENTRA_CLIENT, DOCINDEX_ENTRA_SCOPE and DOCINDEX_ALLOW_USER_OVERRIDE:

msiexec /i CADCoPilot.Inventor.Setup.msi ACCEPTEULA=1 DOCINDEX_URL=https://docindex.corp.example:8644 DOCINDEX_AUTH=windows /qn

A silent install needs ACCEPTEULA=1; see Silent & unattended install.

Pass the properties again on every upgrade, or use the GPO: an upgrade without them removes the values. There is deliberately no property or policy value for a key.

Org portal

An organization admin sets the same things on Org portal → Admin → Document Index: the address, the sign-in kind, the two Entra ids and whether members may override it. Agents pick it up when people sign in. The page stores no secret.

Each person

Desktop agent → Settings → Knowledge → Document index. When the policy or the portal decides, the fields are shown but locked. Test reports who the index thinks you are: “Signed in with your Windows login as CORP\jane: search only.”

The shared-key fallback

Leave "Mode": "ApiKey", set Rag:ApiKey for the service (machine environment variable Rag__ApiKey), and give each person the key to type in Settings → Knowledge. Each PC keeps it with DPAPI. It is never entered in the portal and never sent to SphereHarness.

When it does not work

• 401 — the sign-in was not accepted: a PC off the domain, a missing SPN with NTLM disabled, an Entra token for the wrong tenant or application, or a wrong key.
• 403 — signed in but not in AllowedGroups (or not in WriterGroups for an upload or delete). Group changes apply at the person's next Windows logon.
• The service stops at start — read the Windows event log (Application). A missing certificate, an unwritable index folder, or a missing ASP.NET Core 8 runtime are the usual causes.

See also

• Knowledge Base & Indexing
• Organization Admin Guide
• What goes where