Shinydocs Pro

Search Configuration for File system - Kerberos

What this sets up

When a file system source's Search authentication type is Protected - Negotiate/Kerberos, Search only shows each person the files they can open. Shinydocs Pro checks this by opening the files on the file server as that person, from the Shinydocs Control Center service. Windows only allows this second hop when Kerberos delegation is set up, and that setup is what this page covers.

If you don't need Search to check file permissions, you can skip this page. To add a file system source, see Configure Shinydocs Pro Control Center for File System/File Shares.

How it works

  1. Someone opens Search in their browser. The browser signs them in with Kerberos, using the HTTP SPN registered on the account that runs Shinydocs Control Center.

  2. Search checks that they can open the source's folder, the path you entered when you added the source. If they can't, Search leaves out the whole source for them.

  3. For each result, Control Center opens the file on the file server as that person. The file server only allows this if it trusts the Control Center service account to act for people.

If delegation isn't working, the check in step 2 fails. Search doesn't show an error: it shows the File system connection as disconnected and leaves out its files. Troubleshooting, at the end of this page, lists the usual causes.

Before you start

Write these down. The commands on this page use the examples; replace them with yours.

What you need

Example used on this page

The domain account or group managed service account (gMSA) that will run Shinydocs Control Center

CONTOSO\svc-shinydocs
A gMSA name ends in $, such as CONTOSO\gmsa-shinydocs$

Every name people type to open Control Center

shinydocs01 and shinydocs01.contoso.local, plus any alias, such as shinydocs.contoso.local

Every file server in your source paths

FS01 and FS02, for paths such as \\FS01\Shares

You also need:

  • The Shinydocs Pro server in the same domain as the file servers, with domain controllers running Windows Server 2012 or later.

  • An account that can register SPNs and edit the file servers' computer objects in Active Directory, such as a domain admin.

  • The Active Directory module for PowerShell on the computer you run the commands from. To install it, run this as an administrator:

    PowerShell
    Get-WindowsCapability -Name RSAT.ActiveDirectory* -Online | Add-WindowsCapability -Online
    
  • Control Center signing people in with Windows: under Settings > Access, set Identity provider to Negotiate. With any other identity provider, Search can't check file system permissions and leaves out every protected file system source. See Access and Authentication in Shinydocs Pro.

Step 1: Run Shinydocs Control Center as the service account

Do this on the Shinydocs Pro server.

  1. Make the service account a local administrator: run lusrmgr.msc, open Groups > Administrators, and add the account. Control Center needs this to read and write its settings, database and keys.

  2. Let the account read the HTTPS certificate's private key:

    1. Run certlm.msc and go to Personal > Certificates.

    2. Right-click localhost.localdomain, or the certificate Control Center uses if you changed it, and select All Tasks > Manage Private Keys.

    3. Select Add, find the service account, and select OK.

    4. With the account selected, check Read under Allow, then select OK.

    image-20240229-152929.png
  3. Open Services, right-click Shinydocs Control Center, and select Properties > Log On.

  4. Select This account and enter the service account and its password. For a gMSA, enter the name with its $ and leave both password boxes blank.

  5. Select OK. If Windows says it granted the account the Log on as a service right, select OK again.

  6. Restart the Shinydocs Control Center service.

The Shinydocs Agent service, not Control Center, reads the files for analysis. If you leave Username and Password blank on the File system connection, the agent reads the shares as the account it runs as. See Configure Shinydocs Pro Control Center for File System/File Shares.

Step 2: Register the HTTP SPNs

The browser asks for a Kerberos ticket named after the address it opens, such as HTTP/shinydocs01.contoso.local. Every name people use needs that SPN on the service account. If a name has none, the browser signs in with NTLM instead, and NTLM can't be passed on to the file server.

  1. For each name, check that no account has it yet. You want to see No such SPN found.

    PowerShell
    setspn -Q HTTP/shinydocs01
    setspn -Q HTTP/shinydocs01.contoso.local
    

    An SPN can belong to only one account. If a name is already registered to another account, remove it from that account with setspn -D, or give Shinydocs Pro its own DNS name. This happens when another website on the same server already uses the name.

  2. Register each name, both the short name and the full name, and any alias:

    PowerShell
    setspn -S HTTP/shinydocs01 CONTOSO\svc-shinydocs
    setspn -S HTTP/shinydocs01.contoso.local CONTOSO\svc-shinydocs
    

    For a gMSA, end the account name with $, such as CONTOSO\gmsa-shinydocs$.

  3. Check the account's SPNs:

    PowerShell
    setspn -L CONTOSO\svc-shinydocs
    

Don't add the port (9701) to the SPN. For an alias, use a DNS A record rather than a CNAME, as described in Setting up Shinydocs Control Center for Internal Access.

Step 3: Let the service account act for people on each file server

Each file server keeps a list of accounts that may act for people when they connect to it, called PrincipalsAllowedToDelegateToAccount. Add the Control Center service account to that list on every file server in your source paths.

Add the service account, not the Shinydocs Pro server's computer account. Control Center runs as the service account, so that is the account the file server sees.

Which Active Directory object to use:

  • A file server: its computer name, such as FS01. Use the name, not the full DNS name.

  • A clustered file server: the name of the clustered file server role, as used in the share path, not the cluster's nodes.

  • A DFS path: every server that hosts the namespace or a folder target the path can lead to.

  • A NAS device: the computer account the device uses in Active Directory.

Run this in PowerShell, with your account and file server names. It adds the service account to each file server's list and keeps any accounts already there.

PowerShell
$account = Get-ADUser svc-shinydocs
# For a gMSA, use this instead: $account = Get-ADServiceAccount gmsa-shinydocs

foreach ($name in 'FS01', 'FS02') {
    $fileServer = Get-ADComputer $name -Properties PrincipalsAllowedToDelegateToAccount
    $allowed = @(@($fileServer.PrincipalsAllowedToDelegateToAccount) + $account.DistinguishedName | Select-Object -Unique)
    Set-ADComputer $fileServer -PrincipalsAllowedToDelegateToAccount $allowed
}

Check the result. Each file server should list the service account, for example CN=svc-shinydocs,OU=Service Accounts,DC=contoso,DC=local.

PowerShell
foreach ($name in 'FS01', 'FS02') {
    Get-ADComputer $name -Properties PrincipalsAllowedToDelegateToAccount |
        Select-Object Name, PrincipalsAllowedToDelegateToAccount
}

Set-ADComputer -PrincipalsAllowedToDelegateToAccount replaces the whole list. Don't run it with only the service account if other applications already have entries; use the command above. To clear a file server's list completely, run Set-ADComputer FS01 -PrincipalsAllowedToDelegateToAccount $null.

You don't need to change anything on the Delegation tab of the service account itself.

Step 4: Restart and clear old tickets

  1. Restart the Shinydocs Control Center service on the Shinydocs Pro server.

  2. On each computer you'll test from, sign out of Windows and back in, or run klist purge. Kerberos tickets last up to 10 hours, so a ticket from before your changes can make it look like they didn't work.

Step 5: Protect the source and test

  1. Make sure the File system connection is protected: go to Settings > Connections, select File system, select Edit connection, and check that Search authentication type is Protected - Negotiate/Kerberos. New connections get this setting when you add the source.

  2. On a workstation, not the Shinydocs Pro server, sign in to Windows as a regular domain user who can open some of the files in the source.

  3. Open Search using one of the names you registered, for example https://shinydocs01.contoso.local:9701/search. You should be signed in without being asked for a password.

  4. In the sidebar on the left, the File system connection's plug icon should be green. A grey, faded icon means the connection is disconnected for you. Hover over it to see Connected or Disconnected.

  5. Search for a file you can open; it should appear. Search for a file you can't open; it shouldn't.

  6. To confirm the browser used Kerberos, run klist on the workstation. It should list a ticket for HTTP/ followed by the name you opened. If there isn't one, the browser signed in with NTLM; see Troubleshooting below.

Don't test on the Shinydocs Pro server itself, or with https://localhost:9701. Those sign in with NTLM, which can't be passed on, so file system sources show as disconnected even when the setup is correct.

The browser only signs in automatically when the site is in the Local intranet zone (Internet Options > Security > Local intranet > Sites > Advanced), or allowed by your browser's integrated authentication policy, such as AuthServerAllowlist in Microsoft Edge and Google Chrome.

Troubleshooting

What you see

What to check

The browser asks for a username and password

  • The site isn't in the Local intranet zone or your browser's allow list.

  • The name in the address bar has no HTTP SPN, or its SPN is on another account. Run setspn -Q HTTP/<name>.

  • You opened Control Center by IP address. Use a name you registered.

File system is disconnected for everyone

  • Settings > Access > Identity provider isn't Negotiate.

  • You're testing on the Shinydocs Pro server or through localhost.

  • The Shinydocs Control Center service isn't running as the service account.

  • The service account isn't in the file server's PrincipalsAllowedToDelegateToAccount list, or it was added to the wrong object, such as a cluster node instead of the clustered file server name (Step 3).

  • The source path uses an IP address or an alias the file server has no SPN for. Add sources by the file server's name.

  • Changes were made without restarting the service and clearing tickets (Step 4).

File system is disconnected for some people

  • They can't open the source's folder itself. Search leaves out a source whose folder the person can't open, even if they can open files inside it.

  • Their account is in the Protected Users group, or has Account is sensitive and cannot be delegated set. This is common for administrator accounts; test with a regular account.

File system is connected, but some files the person can open are missing

  • The files were added after the source's last update. Search only finds files that have been analyzed.

  • The Control Center log may show Error checking file access for followed by the file's path, with the reason.

setspn -S says Duplicate SPN found

The name is already registered to another account. setspn -Q HTTP/<name> shows which one.

Remove an SPN

PowerShell
setspn -D HTTP/shinydocs01.contoso.local CONTOSO\svc-shinydocs

Turn on Kerberos logging

On the Shinydocs Pro server, add this registry value. Create the Parameters key if it doesn't exist.

  • Key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters

  • Value: LogLevel, type REG_DWORD, data 0x1

Kerberos errors then appear in the System event log. Set the value back to 0 when you're done. See How to enable Kerberos event logging.

After you add or change SPNs, allow time for them to replicate to all domain controllers.