I recently went looking for an article showing how to configure People Picker for 1-way trusts and was disappointed with what I found. Many articles reference the cringe-worthy STSADM commands. Others are either incomplete or less than concise. So here’s my take on it:

Background:

When using Windows authentication within SharePoint, a domain or forest trust must exist between the domain that SharePoint lives in, and the domain that your user accounts live in. This is a requirement for both People Picker and authentication to work.

Most of the time, the accounts you want People Picker to find are in the local domain, or a 2-way trust is used, in which case, there’s not typically anything special you must do to get People Picker to work. You just configure it normally, specifying which domains / forests you want it to search. For example, this is how you’d configure it to search the whole Contoso forest, and just the “Corp” domain within the Fabrikam forest:

$wa = get-spwebapplication https://theWebApp.contoso.com
$searchad = $wa.peoplepickersettings.searchactivedirectorydomains
$newdomain1 = new-object Microsoft.SharePoint.Administration.sppeoplepickersearchactivedirectorydomain
$newdomain1.domainname = "contoso.com"
$newdomain1.Isforest = $true
$searchad.add($newdomain1)
$newdomain2 = new-object Microsoft.SharePoint.Administration.sppeoplepickersearchactivedirectorydomain
$newdomain2.domainname = "corp.fabrikam.com"
$newdomain2.Isforest = $false
$searchad.add($newdomain2)
$wa.update()  

Why a One-way Trust?

There are many reasons to use a one-way trust instead of a two-way trust. Probably the most common is a “DMZ” scenario, where you have your SharePoint front-ends in a DMZ domain (DMZ.local), and your users are in your internal corporate domain (Contoso.com). In that case, you would set up a one-way trust where the DMZ domain trusts the internal corporate domain, but not vice versa.

Why does People Picker need to be configured differently for a 1-way trust?

By default, People Picker uses the application pool account for the given web app to connect to Active Directory and issue the LDAP queries that People Picker uses to find user accounts. Continuing with my 1-way trust example above, the application pool account would be a DMZ domain account. Since the internal corporate domain (Contoso.com) does not trust the DMZ domain (remember, the trust is only 1-way, and in the opposite direction), there is no way for a DMZ account to authenticate to Contoso. In that case, we need to configure the web application to use Contoso credentials when executing People Picker operations against the Contoso domain.

Step 1: Choose a Connection Account.

Continuing the example above, the app pool account in the DMZ does not have access to your internal domain. In that case, you must manually configure the web app to use a set of credentials from your internal domain.

Considerations for the account:

• It should be a dedicated service account, used only for this purpose.
• The password for the account should change infrequently. – There is no automation within SharePoint to update the password within the People Picker settings, so if you update the password in Active Directory, People Picker will be broken until you update it to match.
• While the password is stored within SharePoint, it is encrypted, and there’s no way to see what it’s currently set to. – If there’s any doubt of its correctness, you’ll have to reconfigure the People Picker settings.

   

Step 2: Set the Encryption Key on each server in the farm.

In step 3, we’ll be specifying a user name and password to connect to the one-way trust domain. For security reasons, that password must be encrypted within SharePoint. To do that, you must specify an encryption key like so:

$key = ConvertTo-SecureString "YourEncryptionKeyHere" -AsPlainText -Force
[Microsoft.SharePoint.SPSecurity]::SetApplicationCredentialKey($key)  

Considerations for the encryption key:

• This key only needs to be set one time per-server. Once it’s been set to the same value across all servers, you can leave it. In the future, this step can be skipped if you configure additional web applications, or change People Picker settings.
• It must be set individually, to the same value, on every SharePoint server in the farm. – Not just the front-ends, but literally every server in the farm.
• The key is stored in the Registry on each server. – That’s why it needs to be individually set on each server in the farm.
• There is no way of telling what you set it to previously, so please document it somewhere.
• There is no attempt to verify that the key you set on one server matches the key on any of the other servers.
• If you add a new server to the farm later, it will not have the encryption key set, and People Picker operations will fail on that server until it’s set to match the other servers.
• If there’s any doubt as to what the key value is, or if it’s set to the same value on each server in the farm, you’ll have to re-set it on each server in the farm to a new value.
• If you update / change the key value, you will then also need to reconfigure all of your one-way trust People Picker settings so that the connection account password is encrypted using the new key. – Basically, re-do Step 3 below.
• SetApplicationCredentialKey is the equivalent of the setapppassword STSADM command, in case you’re more familiar with that.
• In SharePoint 2019 and above, you can use the Set-SPApplicationCredentialKey commandlet instead of the object model method I showed above.

   

Step 3: Configure the People Picker settings, specifying the connection account.

Here’s some sample PowerShell where you specify the connection account, and are then prompted for its password:

$wa = get-spwebapplication "https://theWebApp.contoso.com"
$searchad = $wa.peoplepickersettings.searchactivedirectorydomains
$newdomain = new-object Microsoft.SharePoint.Administration.sppeoplepickersearchactivedirectorydomain
$newdomain.domainname = "Contoso.com"
$newdomain.Isforest = $false
$newdomain.loginname = "contoso\PPAccount"
[System.Security.SecureString]$secureStringValue = Read-Host "Enter the service account password: " -AsSecureString;
$newdomain.setpassword($securestringvalue)
$searchad.add($newdomain)
$wa.update() 

Notes:

• There is no verification that the password you enter is valid for the account you specify. The PowerShell above will happily take a bad password, in which case, People Picker will fail to find any users, and you’ll see an error like this in the ULS logs:
  • w3wp.exe (0x2B2C) 0x168C SharePoint Foundation Performance ftq3 Verbose SearchFromGC name = contoso.com. Error Message: Logon failure: unknown user name or bad password.
    
• If you have a mix of one-way and two-way trusts that you’d like People Picker to search, you can set those all at once. You only need to specify a user name and password for the one-way trust connections. Two-way trust and local forest / domain connections can use the application pool account to connect.

$wa = get-spwebapplication https://theWebApp.contoso.com
$searchad = $wa.peoplepickersettings.searchactivedirectorydomains
$newdomain1 = new-object Microsoft.SharePoint.Administration.sppeoplepickersearchactivedirectorydomain
# Two-way trusted domain or local domain.  No connection account or password required.
$newdomain1.domainname = "fabrikam.com"
$newdomain1.Isforest = $true
$searchad.add($newdomain1)

$newdomain2 = new-object Microsoft.SharePoint.Administration.sppeoplepickersearchactivedirectorydomain
# One-way trust domain.  Must specify connection account and password.
$newdomain2.domainname = "contoso.com"
$newdomain2.Isforest = $false
$newdomain2.loginname = "contoso\PPAccount"
[System.Security.SecureString]$secureStringValue = Read-Host "Enter the service account password: " -AsSecureString;
$newdomain2.setpassword($securestringvalue)
$searchad.add($newdomain2)

$wa.update()