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
-
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.
-
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.
-
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 |
|
|
Every name people type to open Control Center |
|
|
Every file server in your source paths |
|
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:
PowerShellGet-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.
-
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. -
Let the account read the HTTPS certificate's private key:
-
Run
certlm.mscand go to Personal > Certificates. -
Right-click localhost.localdomain, or the certificate Control Center uses if you changed it, and select All Tasks > Manage Private Keys.
-
Select Add, find the service account, and select OK.
-
With the account selected, check Read under Allow, then select OK.
-
-
Open Services, right-click Shinydocs Control Center, and select Properties > Log On.
-
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.
-
Select OK. If Windows says it granted the account the Log on as a service right, select OK again.
-
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.
-
For each name, check that no account has it yet. You want to see No such SPN found.
PowerShellsetspn -Q HTTP/shinydocs01 setspn -Q HTTP/shinydocs01.contoso.localAn 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. -
Register each name, both the short name and the full name, and any alias:
PowerShellsetspn -S HTTP/shinydocs01 CONTOSO\svc-shinydocs setspn -S HTTP/shinydocs01.contoso.local CONTOSO\svc-shinydocsFor a gMSA, end the account name with $, such as
CONTOSO\gmsa-shinydocs$. -
Check the account's SPNs:
PowerShellsetspn -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.
$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.
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
-
Restart the Shinydocs Control Center service on the Shinydocs Pro server.
-
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
-
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.
-
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.
-
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. -
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.
-
Search for a file you can open; it should appear. Search for a file you can't open; it shouldn't.
-
To confirm the browser used Kerberos, run
kliston the workstation. It should list a ticket forHTTP/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 |
|
|
File system is disconnected for everyone |
|
|
File system is disconnected for some people |
|
|
File system is connected, but some files the person can open are missing |
|
|
|
The name is already registered to another account. |
Remove an SPN
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.