Hey, Scripting Guy! Tell Me About Permissions and Using Windows PowerShell 2.0 Cmdlets with SharePoint 2010
Hey, Scripting Guy! What permissions do I need to have in order to use the Windows PowerShell 2.0 cmdlets that ship with SharePoint 2010?
— FJ
Hello FJ,
Microsoft Scripting Guy Ed Wilson here. One of the great things about being a Microsoft Scripting Guy is getting to meet really smart people who use our products. I ran across John Ferringer about a year ago through the scripter@microsoft.com email alias. He was nice enough to give me a copy of his book, and even nicer, he said in the inscription that he hoped I never needed it. His book is about disaster recovery. When I think about working with SharePoint, John is one of the first people who springs to mind. As we continue with Guest Blogger Week, let me introduce John.
John Ferringer is a solutions architect with Apparatus, Inc. He has more than six years of experience administering and supporting SharePoint technologies and has spent more than twelve years working in the technology consulting industry. John is certified as an MCTS on several platforms, including Windows Server 2008, SharePoint, System Center Operations Manager, and Project Server. He has co-authored the SharePoint 2007 Disaster Recovery Guide and is hard at work on the forthcoming SharePoint 2010 Disaster Recovery Guide. Find him at his blog at MyCentralAdmin.com and on Twitter at @Ferringer. Take it away John.
I’m covering what I think is one of the most important aspects of using Windows PowerShell with SharePoint 2010: having the permissions necessary to execute the more than 500 cmdlets that shipped last month with SharePoint 2010 on a server in a farm. The good news is that the SharePoint product team has made this pretty easy to do; it’s light years beyond the minefield you had to navigate to successfully run an STSADM.exe operation in SharePoint 2007. But there are still some things you need to keep in mind.
Recently, I was finishing up the installation of a new SharePoint Server 2010 farm for a customer and I ran into an interesting situation while trying to modify some of the farm’s settings. Everything had gone well up until this point: installed and patched Windows Server 2008 and SQL Server 2008, installed SharePoint 2010, created the farm, got the Central Administration site up and running, and even had a couple of site collections alive and kicking.
But as I started reviewing my results, I realized there were a few chinks in the armor. During the build process, to keep things simple I used SharePoint 2010’s new farm configuration wizard. It worked fine, but I wasn’t thrilled with how it automatically set up a content web application, created a content database for that web application (the helpfully-named WSS_Content database), and placed the root site collection for the MySites managed path in that content database. I wanted to create some new content databases for that web application and get rid of that poor WSS_Content database, but didn’t want to lose the site collection already in the web application.
The comforting thing for me was that this is all pretty easy to do in SharePoint 2010. I created the databases (with much more descriptive names, of course) in SQL Server and joined them to the web application in the Central Administration site. When done, I wanted to delete that WSS_Content database, but it still had that one site collection in it. So first I needed to move the site collection to one of the new content databases, an operation that cannot be done via the Central Administration site.
Enter Windows PowerShell! Because I was remotely connected to the SharePoint server, I opened the SharePoint 2010 Management Shell via the Start menu, and immediately I began to suspect that something was wrong. Windows PowerShell was reporting that it could not find the local SharePoint farm, which I knew the server was running.
I tried not to let it bother me too much and kept on with my original task, which was moving the site collection from WSS_Content to my new content database: FOO_SP_Content. See how much better than name is?. For that task, I would be using the Move-SPSite cmdlet, which is far more enjoyable to use than its SharePoint 2007 equivalent, STSADM’s MergeContentDBs operation. All I needed was the URL of the site I wanted to move and the name of the database I was moving it to:
Move-SPSite http://foo/my -DestinationDatabase FOO_SP_Content
But here’s what I got for my troubles:
I was a bit perplexed; I hadn’t had any issues executing commands in the Central Admin site with the account I was logged in as (a service account I specifically use for installations), which had been granted local admin rights on the SharePoint server as well as dbcreator and securityadmin rights in the farm’s SQL Server instance. It was also named as an administrator of the SharePoint farm with which I was working, so I started thinking about what might be causing my problem and doing some investigation on the server.
Immediately I turned to a critical SharePoint 2010 cmdlet, Add-SPShellAdmin. Now, here’s where it gets interesting. So what does Add-SPShellAdmin do? As you can probably infer from the name, it grants administrative rights to a named user’s account in SharePoint via Windows PowerShell. This is a big deal, trust me. Want proof? Look up pretty much any documented process on SharePoint 2010 in TechNet that involves Windows PowerShell (try this for example: http://technet.microsoft.com/en-us/library/ee428315.aspx), and check to see if it mentions having access granted via Add-SPShellAdmin as a prerequisite. Go ahead, I’ll wait for you. Are you back? It did, didn’t it? Now, this may not be universally true, but I bet it’s pretty close.
Now, there are some specific things that the Add-SPShellAdmin cmdlet does to grant those SharePoint administrative rights, and I want to cover that before getting back to my issue. Add-SPShellAdmin grants targeted accounts the following rights:
- The user is added to the SharePoint_Shell_Access role (if this role does not exist in the target database, the cmdlet creates it). This is important to note, because the assignment of that role grants the user SQL Server’s db_owner and securityadmin rights in the database targeted by the cmdlet, something that should not be taken lightly.
- Add-SPShellAdmin can be used to target specific databases within your farm via the –database input parameter. If you specify a database, the user is granted those rights in the farm’s configuration database, the Central Admin site’s content database, and the targeted database. If you do not specify a database, the cmdlet grants the user rights for the farm’s configuration database by default.
- The user is also added to the WSS_ADMIN_WPG local security group on all servers in the farm with the SharePoint Foundation 2010 Web Application role, which grants certain administrative rights in IIS and the file system of those affected servers.
As you can see, these are certainly nontrivial rights within your farm and should be granted only to administrators who you trust to use those powers properly. A single misstep with these rights can have a pretty drastic negative impact on your environment, and that’s something I would encourage you to impress upon any administrator you grant them to.
Now let’s get back to my problem. Based on the error above, I was beginning to think that the account I was using had not been assigned these rights, and if I was going to move that site collection to another database, I was going to need them. So the first thing I did was check to see which users had been assigned rights in the farm via Add-SPShellAdmin, using the Get-SPShellAdmin cmdlet.
Okay, so I thought maybe I could just go ahead and add my account to the role using AddSPShellAdmin, as shown in the following image.
Ugh. I knew it was already a local administrator, so at this point I was pretty sure the account I was using was no good. But here’s the thing: This farm still has that “new farm” smell. I had the only user administrator account in the farm, but how was I going to grant it rights if I couldn’t use the cmdlet with my account? So I did some digging and figured out which rights are necessary to be able to use the Add-SPShellAdmin cmdlet:
- Membership in the db_owner and securityadmin roles in the farm’s SQL Server instance.
- Local administrative rights on the server from which you’re running the cmdlet.
Well, there is one account that by default has these rights and therefore the ability to use Add-SPShellAdmin: the SharePoint farm’s Database Access Account, also known as the “farm account.” So I dug up the password I had assigned to that account, logged in with it, and fired up the SharePoint 2010 Management Shell to grant those rights to my administrator account.
Looking good so far.
Woohoo!
Yep, I was cooking with gas. Or so I thought. So I logged out of the server as the farm account and re-entered it with my administrative account and fired up the SharePoint 2010 Management Shell. It opened just fine, which had me feeling good, so I tried using it to grant another user’s account administrator rights in the farm for Windows PowerShell:
Crud. For that matter, the Move-SPSite cmdlet didn’t work either. Now I was a bit annoyed because I knew this account was a local administrator. So I thought about it some more and went back to reviewing the rights granted by Add-SPShellAdmin to see what I had missed. I checked the databases, and the account had the proper roles in all the farm’s databases I would be touching. I checked the Administrators group on the server, and the account was in it. But then I started thinking about those local rights and checked something else: User Access Control (UAC).
This farm had been a pretty vanilla installation so far from top to bottom, so I hadn’t taken the time to configure the Windows Server 2008 operating system exactly the way I wanted and had left UAC enabled. Now, whether or not it should be on in a server operating system is a discussion for another day, but on this day it was on the verge of giving me an ulcer. So I turned it off. And voila! Everything worked.
So remember, when using the SharePoint 2010 Management Shell and its Windows PowerShell cmdlets, you need both the rights discussed above granted via the Add-SPShellAdmin cmdlet and local administrator rights on the server on which you’re running the management shell, established either by turning off UAC or by running the shell as sdministrator from the Start menu.
FJ, that is all there is to understanding the permissions required to use the SharePoint 2010 Windows PowerShell cmdlets. Guest Blogger Week will continue tomorrow.
If you want to know exactly what we will be looking at tomorrow, follow us on Twitter or Facebook. If you have any questions, send e-mail to us at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson and Craig Liebendorfer, Scripting Guys
Light
Dark
0 comments