Configure Object Caching accounts using PowerShell

If you want your Object Caching to work properly in SharePoint, you need to set 2 user accounts:

  • Portal Super Reader
  • Portal Super User

Additionally, they must be configured correctly. That is, you need to do 2 things:

  • Add a “Full Control” user policy to your web application for the Portal Super User and use PowerShell to create a web application property “portalsuperuseraccount” which has a value that’s exactly the same as the displayname of that user in the user policy.
  • Add a “Full Read” user policy to your web application for the Portal Super Reader and use PowerShell to create a web application property “portalsuperreaderaccount” which has a value that’s exactly the same as the displayname of that user in the user policy.

A lot of mistakes are made when doing this manually as a result of typo’s. Especially when you are working with claims.

To avoid this, you can use the script below to do the necessary actions. You simply provide the URL of the web application and both user accounts and the script will do the rest.

<#
.SYNOPSIS
   Sets the Object Caching accounts

.DESCRIPTION
   Sets the 2 user accounts (Portal Super User and Portal Super Reader) for the Object Caching for a webapplication.
   Requires 2 existing domain accounts.

.NOTES
   File Name: Add-WebApplicationPolicy.ps1
   Author   : Bart Kuppens
   Version  : 1.1
   Changes  :
      Date        Version Description
      ----        ------- -----------
      23/06/2016   1.1    Define user policy for '(All Zones)' instead of 'Default' zone

.PARAMETER Webapplication
   Web application URL

.PARAMETER Superuser
   Domain account for the Portal Super User in the format 'domain\username'

.PARAMETER Superreader
   Domain account for the Portal Super Reader in the format 'domain\username'

.EXAMPLE
   PS > .\Add-WebApplicationPolicy.ps1 -Webapplication http://intranet.ctgdemo.com -Superuser ctgdemo\superuser -Superreader ctgdemo\superreader

   Description
   -----------
   This script gives the ctgdemo\superuser account "Full Control" and the ctgdemo\superreader account "Full Read" permissions on the specified webapplication
#>

param(
   [parameter(Position=0,Mandatory=$true,ValueFromPipeline=$true)]
   [string]$Webapplication,
   [parameter(Position=1,Mandatory=$true,ValueFromPipeline=$false)]
   [string]$Superuser,
   [parameter(Position=2,Mandatory=$true,ValueFromPipeline=$false)]
   [string]$Superreader
)

# Load SharePoint snapin if needed
if ((Get-PSSnapin -Name Microsoft.SharePoint.PowerShell -ErrorAction SilentlyContinue) -eq $null)
{
   Write-Host "Loading SharePoint cmdlets..."
   Add-PSSnapin Microsoft.SharePoint.PowerShell
}

# Validate parameters
$webApp = Get-SPWebApplication $Webapplication
if ($webApp -eq $null)
{
   Write-Host "'$webapplication' is not a valid SharePoint webapplication"
   break
}

# Convert plain user names to Claims if the webapp uses Claims Based authentication
if ($webApp.UseClaimsAuthentication)
{
   $cpSUser = New-SPClaimsPrincipal -Identity $Superuser -IdentityType WindowsSamAccountName
   $Superuser = $cpSUser.ToEncodedString()
   $cpSReader = New-SPClaimsPrincipal -Identity $Superreader -IdentityType WindowsSamAccountName
   $Superreader = $cpSReader.ToEncodedString()
}

# Check if a Web Application Policy already exists for the Portal Super User Account
$policy = $webApp.Policies | Where {$_.UserName.ToLower() -eq $Superuser.ToLower()}
if ($policy -eq $null)
{
   $policy = $webapp.Policies.Add($Superuser, "Portal Super User Account")
   $fc = $webApp.PolicyRoles.GetSpecialRole("FullControl")
   $policy.PolicyRoleBindings.Add($fc)
   $webApp.Properties["portalsuperuseraccount"] = $Superuser
   $webApp.Update()
}
else
{
   Write-Host "Policy for $Superuser already exists"
}

# Check if a Web Application Policy already exists for the Portal Super Reader Account
$policy = $webApp.Policies | Where {$_.UserName.ToLower() -eq $Superreader.ToLower()}
if ($policy -eq $null)
{
   $policy = $webapp.Policies.Add($Superreader, "Portal Super Reader Account")
   $fc = $webApp.PolicyRoles.GetSpecialRole("FullRead")
   $policy.PolicyRoleBindings.Add($fc)
   $webApp.Properties["portalsuperreaderaccount"] = $Superreader
   $webApp.Update()
}
else
{
   Write-Host "Policy for $Superreader already exists"
}

And voila, your life just got a little less complicated. 🙂

By Bart

Bart is a certified SharePoint consultant / architect at CTG Belgium NV with a broad professional experience in IT, a background in software development with a specialisation in Microsoft products and technologies and a solid knowledge and experience in Microsoft SharePoint Products and Technologies. He started as a COBOL developer on a mainframe environment and grew into software development for Windows platforms. Participated in projects varying from migrations of existing applications to development of Web applications and Windows applications. Became fascinated by the SharePoint 2007 platform and strongly believed in the added business value of this platform. Is since then fully committed to SharePoint and focuses on SharePoint implementations, migrations, integrations, design and coaching. Stays on top of new developments within the SharePoint technology stack and related technologies.